---
layout: docs
page_title: 'nomad alloc fs command reference'
description: |
  The `nomad alloc fs` lets you navigate an allocation working directory on a Nomad client.
---

# `nomad alloc fs` command reference

**Alias: `nomad fs`**

The `alloc fs` command allows a user to navigate an [allocation working
directory] on a Nomad client. The following functionalities are available -
`cat`, `tail`, `ls` and `stat`.

- `cat`: If the target path is a file, Nomad will `cat` the file.

- `tail`: If the target path is a file and `-tail` flag is specified, Nomad will
  `tail` the file.

- `ls`: If the target path is a directory, Nomad displays the name of a file and
  directories and their associated information.

- `stat`: If the `-stat` flag is used, Nomad will display information about a
  file.

## Usage

```plaintext
nomad alloc fs [options] <allocation> <path>
```

This command accepts a single allocation ID (unless the `-job` flag is
specified, in which case an allocation is chosen from the given job) and a
path. The path is optional and relative to the root of the [allocation working
directory].

When ACLs are enabled, this command requires a token with the `read-fs`,
`read-job`, and `list-jobs` capabilities for the allocation's namespace.

### Use Job ID instead of Allocation ID

Setting the `-job` flag causes a random allocation of the specified job to be
selected. Nomad prefers selecting a running allocation ID for the job, but
if no running allocations for the job are found, Nomad uses a dead
allocation.

```plaintext
nomad alloc fs -job <job-id> <path>
```

This can be useful for debugging a job that has multiple allocations, and it is
not required to observe a specific allocation.

## Options

- `-H`: Machine friendly output.

- `-verbose`: Display verbose output.

- `-job=<job-name|job-id>`: Use a random allocation from the specified job or
  job ID prefix, preferring a running allocation.

- `-group=<group-name>`: Specifies the task group where the task is located
  when a random allocation is selected

- `-stat`: Show stat information instead of displaying the file, or listing the
  directory.

- `-f`: Causes the output to not stop when the end of the file is reached, but
  rather to wait for additional output.

- `-tail`: Show the files contents with offsets relative to the end of the file.
  If no offset is given, -n is defaulted to 10.

- `-n`: Sets the tail location in best effort number of lines relative to the
  end of the file.

- `-c`: Sets the tail location in number of bytes relative to the end of the file.

## Examples

```shell-session
$ nomad alloc fs eb17e557
Mode        Size  Modified Time        Name
drwxrwxr-x  4096  28 Jan 16 05:39 UTC  alloc/
drwxrwxr-x  4096  28 Jan 16 05:39 UTC  redis/
-rw-rw-r--  0     28 Jan 16 05:39 UTC  redis_exit_status


$ nomad alloc fs eb17e557 redis/local
Mode        Size  Modified Time        Name
-rw-rw-rw-  0     28 Jan 16 05:39 UTC  redis.stderr
-rw-rw-rw-  17    28 Jan 16 05:39 UTC  redis.stdout


$ nomad alloc fs -stat eb17e557 redis/local/redis.stdout
Mode        Size  Modified Time        Name
-rw-rw-rw-  17    28 Jan 16 05:39 UTC  redis.stdout


$ nomad alloc fs eb17e557 redis/local/redis.stdout
foobar
baz

$ nomad alloc fs -tail -f -n 3 eb17e557 redis/local/redis.stdout
foobar
baz
bam
<blocking>
```

## General options

@include 'general_options.mdx'

[allocation working directory]: /nomad/docs/reference/runtime-environment-settings#task-directories 'Task Directories'
